# output.cssModules

- **Type:** `CSSModules`

For custom CSS Modules configuration.

The CSS Modules feature of Rsbuild is based on the `modules` option of css-loader. You can refer to [css-loader - modules](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#modules) to learn more.

## cssModules.auto

The `auto` configuration option allows CSS Modules to be automatically enabled based on their filenames.

- **Type:**

```ts
type Auto =
  | boolean
  | RegExp
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: string,
    ) => boolean);
```

- **Default:** `true`

Type description:

- `true`: enable CSS Modules for all files matching `/\.module\.\w+$/i.test(filename)` regexp.
- `false`: disable CSS Modules.
- `RegExp`: enable CSS Modules for all files matching `/RegExp/i.test(filename)` regexp.
- `function`: enable CSS Modules for files based on the filename satisfying your filter function check.

```ts
export default {
  output: {
    cssModules: {
      auto: (resource) => {
        return resource.includes('.module.') || resource.includes('shared/');
      },
    },
  },
};
```

## cssModules.exportLocalsConvention

Style of exported class names.

- **Type:**

```ts
type CSSModulesLocalsConvention =
  | 'asIs'
  | 'camelCase'
  | 'camelCaseOnly'
  | 'dashes'
  | 'dashesOnly';
```

- **Default:** `'camelCase'`

Type description:

- `asIs`: Class names will be exported as is.
- `camelCase`: Class names will be camelized, the original class name will be exported.
- `camelCaseOnly`: Class names will be camelized, the original class name will not be exported.
- `dashes`: Only dashes in class names will be camelized, the original class name will be exported.
- `dashesOnly`: Dashes in class names will be camelized, the original class name will not be exported.

```ts
export default {
  output: {
    cssModules: {
      exportLocalsConvention: 'camelCaseOnly',
    },
  },
};
```

## cssModules.exportGlobals

- **Type:** `boolean`
- **Default:** `false`

Allows exporting names from global class names, so you can use them via import.

### Example

Set the `exportGlobals` to `true`:

```ts
export default {
  output: {
    cssModules: {
      exportGlobals: true,
    },
  },
};
```

Use `:global()` in CSS Modules:

```css title="style.module.css"
:global(.blue) {
  color: blue;
}

.red {
  color: red;
}
```

Then you can import the class name wrapped with `:global()`:

```tsx title="Button.tsx"
import styles from './style.module.css';

console.log(styles.blue); // 'blue'
console.log(styles.red); // 'red-[hash]'
```

## cssModules.localIdentName

- **Type:** `string`
- **Default:**

```ts
// isProd indicates that the production build
const localIdentName = isProd
  ? '[local]-[hash:base64:6]'
  : '[path][name]__[local]-[hash:base64:6]';
```

Sets the format of the class names generated by CSS Modules after compilation.

### Default Value

`localIdentName` has different default values in development and production.

In a production, Rsbuild will generate shorter class names to reduce the bundle size.

```ts
import styles from './index.module.scss';

// In development, the value is `src-index-module__header-[hash]`
// In production, the value is `header-[hash]`
console.log(styles.header);
```

### Template String

You can use the following template strings in `localIdentName`:

- `[name]` - the basename of the asset.
- `[local]` - original class.
- `[hash]` - the hash of the string.
- `[folder]` - the folder relative path.
- `[path]` - the relative path.
- `[file]` - filename and path.
- `[ext]` - extension with leading dot.
- `[hash:<hashDigest>:<hashDigestLength>]`: hash with hash settings.

### Example

Set `localIdentName` to other value:

```ts
export default {
  output: {
    cssModules: {
      localIdentName: '[hash:base64:4]',
    },
  },
};
```

## cssModules.mode

- **Type:**

```ts
type Mode =
  | 'local'
  | 'global'
  | 'pure'
  | 'icss'
  | ((resourcePath: string) => 'local' | 'global' | 'pure' | 'icss');
```

- **Default:** `'local'`

Controls the mode of compilation applied to the CSS Modules.

### Optional values

`cssModules.mode` can take one of the following values:

1. `'local'` (default): This enables the CSS Modules specification for scoping CSS locally. Class and ID selectors are rewritten to be module-scoped, and `@value` bindings are injected.
2. `'global'`: This opts-out of the CSS Modules behavior, disabling both local scoping and injecting `@value` bindings. Global selectors are preserved as-is.
3. `'pure'`: This enables dead-code elimination by removing any unused local classnames and values from the final CSS. It still performs local scoping and `@value` injection.
4. `'icss'`: This compiles to the low-level Interoperable CSS format, which provides a syntax for declaring `:import` and `:export` dependencies between CSS and other languages. It does not perform any scoping or `@value` injection.

The `'local'` mode is the most common use case for CSS Modules, enabling modular and locally-scoped styles within components. The other modes may be used in specific scenarios.

For example:

```ts
export default {
  output: {
    cssModules: {
      mode: 'global',
    },
  },
};
```

### Function

You can also pass a function to `modules.mode` that determines the mode based on the resource path, query, or fragment. This allows you to use different modes for different files.

For example, to use local scoping for `.module.css` files and global styles for other files:

```js
modules: {
  mode: (resourcePath) => {
    if (/\.module\.\css$/.test(resourcePath)) {
      return 'local';
    }
    return 'global';
  };
}
```

## cssModules.namedExport

- **Type:** `boolean`
- **Default:** `false`

Whether to enable ES modules named export for class names.

```ts
export default {
  output: {
    cssModules: {
      namedExport: true,
    },
  },
};
```

### Example

```css title="style.module.css"
.foo {
  color: blue;
}
```

- `namedExport: false`:

```js
import styles from './style.module.css';

console.log(styles.foo);
```

- `namedExport: true`:

```js
import { foo } from './style.module.css';
// or
import * as styles from './style.module.css';

console.log(foo);
console.log(styles.foo);
```

:::tip
When `namedExport` is set to true, the `default` class exported by CSS Modules will be automatically renamed to `_default` class because `default` is a reserved word in ECMA modules.
:::
